<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.5">
<meta name="author" content="2019-08-08 13:15:33 CEST">
<title>N4JS Design Specification</title>
<link rel="stylesheet" href="styles/spec.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
<!-- ************* docinfo ******************************************************************* -->


<!-- ************* Favicon ************-->
<link rel="icon" href="images/favicon.ico" />

<!-- ************* Back-to-top JQuery ************* -->
<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>


<link href="styles/prism.min.css" rel="stylesheet" />
<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

<!-- ************* Styles ************* -->
<link rel="stylesheet" type="text/css" href="styles/n4jsspec-adoc.css">


<!-- ****************** NavBar ****************** -->
<div id="menubar">
	<div class="banner">
        <a href="https://www.eclipse.org/n4js/#"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS"></a>
    </div>
<ul>
  <li><a href="index.html">Index</a></li>
</ul>
</div>
<!-- ************* docinfo ******************************************************************* -->
<style>
      .admonitionblock td.icon .icon-todo:before{content:"\f249";color:#f4ee42}
    </style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>N4JS Design Specification</h1>
<div class="details">
<span id="author" class="author">2019-08-08 13:15:33 CEST</span><br>
<span id="revnumber">version 0.9</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="introduction.html#_introduction">1. Introduction</a>
<ul class="sectlevel2">
<li><a href="introduction.html#notation">1.1. Notation</a></li>
<li><a href="introduction.html#sec:IDE_Overview">1.2. IDE Components</a>
<ul class="sectlevel3">
<li><a href="introduction.html#sec:Naming_Conventions">1.2.1. Naming Conventions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="eclipse_setup.html#_eclipse-setup">2. Eclipse Setup</a>
<ul class="sectlevel2">
<li><a href="eclipse_setup.html#_system-requirements">2.1. System Requirements</a></li>
<li><a href="eclipse_setup.html#_contribute">2.2. Contribute</a>
<ul class="sectlevel3">
<li><a href="eclipse_setup.html#_eclipse-installer">2.2.1. Eclipse Installer</a>
<ul class="sectlevel4">
<li><a href="eclipse_setup.html#_changing-the-setup-script">2.2.1.1. Changing the Setup Script</a></li>
</ul>
</li>
<li><a href="eclipse_setup.html#_manual-ide-configuration">2.2.2. Manual IDE Configuration</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="release_engineering.html#_release-engineering">3. Release Engineering</a>
<ul class="sectlevel2">
<li><a href="release_engineering.html#_nightly-build-on-eclipse-infrastructure">3.1. Nightly build on Eclipse infrastructure</a></li>
<li><a href="release_engineering.html#_build-the-n4js-ide-from-command-line">3.2. Build the N4JS IDE from command line</a>
<ul class="sectlevel3">
<li><a href="release_engineering.html#_publish-maven-tooling-code-org-eclipse-n4js-releng-util-code">3.2.1. Publish maven-tooling <code>org.eclipse.n4js.releng.util</code></a></li>
<li><a href="release_engineering.html#sec:test-verdaccio">3.2.2. Test Verdaccio containing n4js-libs</a></li>
<li><a href="release_engineering.html#_generation-of-eclipse-help-for-spec-and-design-document">3.2.3. Generation of Eclipse help for spec and design document</a></li>
</ul>
</li>
<li><a href="release_engineering.html#_updating-frameworks-and-dependencies">3.3. Updating frameworks and dependencies</a>
<ul class="sectlevel3">
<li><a href="release_engineering.html#_update-of-eclipse-emf-xtext-etc">3.3.1. Update of Eclipse, EMF, Xtext, etc.</a></li>
<li><a href="release_engineering.html#_update-of-the-embedded-jre">3.3.2. Update of the embedded JRE</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tips_and_tricks.html#_tips-and-tricks">4. Tips and Tricks</a>
<ul class="sectlevel2">
<li><a href="tips_and_tricks.html#_naming">4.1. Naming</a></li>
<li><a href="tips_and_tricks.html#_logging">4.2. Logging</a></li>
<li><a href="tips_and_tricks.html#_cancellation-handling">4.3. Cancellation Handling</a></li>
<li><a href="tips_and_tricks.html#_caching">4.4. Caching</a></li>
<li><a href="tips_and_tricks.html#_dependency-injection">4.5. Dependency Injection</a></li>
<li><a href="tips_and_tricks.html#_miscellaneous">4.6. Miscellaneous</a></li>
</ul>
</li>
<li><a href="parser.html#_parser">5. Parser</a>
<ul class="sectlevel2">
<li><a href="parser.html#sec:Parser_Overview">5.1. Overview</a></li>
<li><a href="parser.html#sec:N4JS_Parser">5.2. N4JS Parser</a></li>
<li><a href="parser.html#sec:Parser_Generation_Post_Processing">5.3. Parser Generation Post-Processing</a>
<ul class="sectlevel3">
<li><a href="parser.html#sec:Automatic_Semicolon_Insertion">5.3.1. Automatic Semicolon Insertion</a>
<ul class="sectlevel4">
<li><a href="parser.html#sec:Injected_code_in_the_Antlr_grammar_file">5.3.1.1. Injected code in the Antlr grammar file</a></li>
<li><a href="parser.html#sec:Customized_error_recovery">5.3.1.2. Customized error recovery</a></li>
</ul>
</li>
<li><a href="parser.html#sec:_No_line_terminator_allowed_here__handling">5.3.2. Async and <code>No line terminator allowed here</code> Handling</a></li>
<li><a href="parser.html#sec:Regular_Expression">5.3.3. Regular Expression</a></li>
<li><a href="parser.html#sec:Unicode">5.3.4. Unicode</a></li>
<li><a href="parser.html#sec:Literals">5.3.5. Literals</a></li>
</ul>
</li>
<li><a href="parser.html#sec:Modifiers">5.4. Modifiers</a></li>
<li><a href="parser.html#sec:Conflict_Resolutions">5.5. Conflict Resolutions</a>
<ul class="sectlevel3">
<li><a href="parser.html#sec:Reserved_Keywords_vs__Identifier_Names">5.5.1. Reserved Keywords vs. Identifier Names</a></li>
<li><a href="parser.html#sec:Operators_and_Generics">5.5.2. Operators and Generics</a></li>
</ul>
</li>
<li><a href="parser.html#sec:Content_Assist_Parser">5.6. Content-Assist Parser</a></li>
</ul>
</li>
<li><a href="type_system.html#_type-system">6. Type System</a>
<ul class="sectlevel2">
<li><a href="type_system.html#sec:Type_Model_and_Grammar">6.1. Type Model and Grammar</a>
<ul class="sectlevel3">
<li><a href="type_system.html#sec:Type_Model_Overview">6.1.1. Type Model Overview</a></li>
<li><a href="type_system.html#sec:Built_in_Types">6.1.2. Built-in and Primitive Types</a></li>
<li><a href="type_system.html#sec:Type_Model_DSL">6.1.3. Type Model DSL</a></li>
</ul>
</li>
<li><a href="type_system.html#sec:Type_System_Implementation">6.2. Type System Implementation</a></li>
<li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal">6.3. Type Inference of AST</a>
<ul class="sectlevel3">
<li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal__Background">6.3.1. Background</a></li>
<li><a href="type_system.html#sec:Triggering_Type_Inference_of_AST">6.3.2. Triggering</a></li>
<li><a href="type_system.html#sec:Traversal_Order_During_Type_Inference_of_AST">6.3.3. Traversal Order</a></li>
<li><a href="type_system.html#sec:Cross_References_During_Type_Inference_of_AST">6.3.4. Cross-References</a></li>
<li><a href="type_system.html#sec:Function_Accessor_Bodies_During_Type_Inference_of_AST">6.3.5. Function/Accessor Bodies</a></li>
<li><a href="type_system.html#sec:Poly_Expressions_During_Type_Inference_of_AST">6.3.6. Poly Expressions</a></li>
<li><a href="type_system.html#sec:Constraint_Solver_used_During_Type_Inference_of_AST">6.3.7. Constraint Solver</a></li>
<li><a href="type_system.html#sec:Type_Guards_During_Type_Inference_of_AST">6.3.8. Type Guards</a></li>
</ul>
</li>
<li><a href="type_system.html#sec:Structural_Typing">6.4. Structural Typing</a></li>
</ul>
</li>
<li><a href="type_index.html#_type-index">7. Type Index</a>
<ul class="sectlevel2">
<li><a href="type_index.html#sec:Type_Index_Design_Rationale">7.1. Design Rationale</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Getting_the_Xtext_Index_Content_IResourceDescriptions">7.1.1. Getting the Xtext Index (<code>IResourceDescriptions</code>) Content</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Design_Overview">7.2. Design Overview</a></li>
<li><a href="type_index.html#sec:N4JS_Resource_Load_States">7.3. N4JS Resource Load States</a></li>
<li><a href="type_index.html#sec:Type_Builder">7.4. Types Builder</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Type_Inference_not_allowed_in_Type_Builder">7.4.1. Type Inference not allowed in Types Builder</a></li>
<li><a href="type_index.html#sec:ComputedTypeReferences">7.4.2. Deferred Type References</a></li>
<li><a href="type_index.html#sec:Use_cases_of_ComputedTypeRef">7.4.3. Use cases of DeferredTypeRef</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview">7.5. Incremental Builder (Overview)</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Incremental_Builder_Overview__XtextBuilder">7.5.1. XtextBuilder</a></li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview__IBuilderState">7.5.2. IBuilderState</a>
<ul class="sectlevel4">
<li><a href="type_index.html#copy-and-update-xtext-index">7.5.2.1. Copy and Update Xtext Index</a></li>
<li><a href="type_index.html#build-state-setup-phase">7.5.2.2. Build State Setup Phase</a></li>
<li><a href="type_index.html#process-queued-uris">7.5.2.3. Process Queued URIs</a></li>
<li><a href="type_index.html#queueing-affected-resources">7.5.2.4. Queueing Affected Resources</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview__Example">7.5.3. Example</a></li>
</ul>
</li>
<li><a href="type_index.html#dirty-state-handling">7.6. Dirty state handling</a>
<ul class="sectlevel3">
<li><a href="type_index.html#use-case-restoring-types-from-user-data">7.6.1. Use case: Restoring types from user data</a></li>
<li><a href="type_index.html#use-case-updating-the-xtext-index">7.6.2. Use case: Updating the Xtext index</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="project_model.html#_project-model">8. Project Model</a>
<ul class="sectlevel2">
<li><a href="project_model.html#sec:Package_json">8.1. Package.json File</a></li>
<li><a href="project_model.html#_accessing-project-information">8.2. Accessing Project Information</a>
<ul class="sectlevel3">
<li><a href="project_model.html#sec:IN4JSCore">8.2.1. IN4JSCore</a></li>
<li><a href="project_model.html#sec:N4JSModel">8.2.2. N4JSModel</a></li>
<li><a href="project_model.html#sec:N4JSWorkspace">8.2.3. N4JSWorkspace</a></li>
<li><a href="project_model.html#sec:N4JSProject">8.2.4. N4JSProject</a></li>
<li><a href="project_model.html#sec:SourceContainer">8.2.5. SourceContainer</a></li>
<li><a href="project_model.html#sec:N4JSProjectsStateHelper">8.2.6. N4JSProjectsStateHelper</a></li>
</ul>
</li>
<li><a href="project_model.html#sec:Caching">8.3. Caching</a>
<ul class="sectlevel3">
<li><a href="project_model.html#_caching-of-externallibraryworkspace">8.3.1. Caching of ExternalLibraryWorkspace</a></li>
<li><a href="project_model.html#_caching-of-n4jsprojectsstatehelper">8.3.2. Caching of N4JSProjectsStateHelper</a></li>
</ul>
</li>
<li><a href="project_model.html#sec:WildcardPathFilter">8.4. WildcardPathFilter</a></li>
<li><a href="project_model.html#sec:ProjectUtils">8.5. ProjectUtils</a></li>
</ul>
</li>
<li><a href="binding.html#_binding">9. Binding</a>
<ul class="sectlevel2">
<li><a href="binding.html#sec:Binding_Design_Rationale">9.1. Design Rationale</a></li>
<li><a href="binding.html#sec:Binding_to_Members">9.2. Binding to Members</a></li>
<li><a href="binding.html#sec:Binding_Getter_Setter">9.3. Getter / Setter Binding</a></li>
<li><a href="binding.html#chap:Statics">9.4. Static Member Binding</a></li>
<li><a href="binding.html#sec:Binding_Enumeration">9.5. Enumeration Literals Binding</a></li>
<li><a href="binding.html#sec:Accessibility_of_types_and_members">9.6. Accessibility of types and members</a></li>
<li><a href="binding.html#sec:Member_Scope_Example">9.7. Member Scope Example</a></li>
<li><a href="binding.html#sec:Scoping_for_Members_of_Composed_Type_Explained">9.8. Scoping for Members of Composed Type (Union/Intersection) Example</a></li>
<li><a href="binding.html#sec:Binding_of_Structurally_References_Types">9.9. Structurally References Types</a></li>
<li><a href="binding.html#sec:Building">9.10. Building</a>
<ul class="sectlevel3">
<li><a href="binding.html#sec:Build_Phases">9.10.1. Build Phases</a></li>
<li><a href="binding.html#sec:Build_Scenarios">9.10.2. Build Scenarios</a></li>
<li><a href="binding.html#sec:Lazy_linking_problem">9.10.3. Lazy linking problem</a></li>
</ul>
</li>
<li><a href="binding.html#sec:Proxies_and_Proxy_Resolution">9.11. Proxies and Proxy Resolution (Overview)</a>
<ul class="sectlevel3">
<li><a href="binding.html#xtexts-lazy-linking-proxies">9.11.1. Xtext’s Lazy Linking Proxies</a></li>
<li><a href="binding.html#standard-emf-proxies">9.11.2. Standard EMF Proxies</a></li>
<li><a href="binding.html#_how-is-proxy-resolution-triggered">9.11.3. How is Proxy Resolution Triggered?</a></li>
<li><a href="binding.html#_when-is-proxy-resolution-allowed">9.11.4. When is Proxy Resolution Allowed?</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="validation.html#_validation">10. Validation</a>
<ul class="sectlevel2">
<li><a href="validation.html#sec:validation_overview">10.1. Validation overview</a></li>
<li><a href="validation.html#sec:validation_control_flow">10.2. Validation control flow</a></li>
<li><a href="validation.html#sec:validation_issue_ids">10.3. Issue IDs and Messages</a></li>
<li><a href="validation.html#sec:validation_usage_patterns">10.4. Usage Pattern</a></li>
<li><a href="validation.html#sec:validation_links">10.5. Links</a></li>
</ul>
</li>
<li><a href="#_references">11. References</a>
<ul class="sectlevel2">
<li><a href="#sec:usecases">11.1. Use cases</a></li>
<li><a href="#sec:calculation_algorithm">11.2. Calculation algorithm</a>
<ul class="sectlevel3">
<li><a href="#sec:Xtext_default_implementation">11.2.1. Xtext default implementation</a></li>
<li><a href="#sec:N4_implementation">11.2.2. N4JS implementation</a></li>
</ul>
</li>
<li><a href="#sec:PerformanceOfDependencyCalculation">11.3. Performance Of Dependency Calculation</a></li>
<li><a href="#sec:kinds_of_references">11.4. Kinds of references</a>
<ul class="sectlevel3">
<li><a href="#sec:Cross_References_to_be_ignored">11.4.1. Cross References to be ignored</a></li>
<li><a href="#sec:Cross_References_to_be_handled">11.4.2. Cross References to be handled</a></li>
</ul>
</li>
<li><a href="#sec:transitive_dependencies">11.5. Transitive dependencies</a></li>
<li><a href="#sec:find-references">11.6. Find references</a>
<ul class="sectlevel3">
<li><a href="#_background">11.6.1. Background</a></li>
<li><a href="#_how-find-references-work">11.6.2. How Find References Work</a>
<ul class="sectlevel4">
<li><a href="#_step-1-convert-cursor-position-to-declared-element">11.6.2.1. Step 1: Convert Cursor Position to Declared Element</a></li>
<li><a href="#_step-2-convert-declared-element-to-target-uris">11.6.2.2. Step 2: Convert Declared Element to Target URIs</a></li>
<li><a href="#_step-3-filter-potential-resources">11.6.2.3. Step 3: Filter Potential Resources</a></li>
<li><a href="#_step-4-search-references-in-resource">11.6.2.4. Step 4: Search References in Resource</a></li>
<li><a href="#_limitations-and-possible-enhancements">11.6.2.5. Limitations and Possible Enhancements</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="compilation.html#_compilation">12. Compilation</a>
<ul class="sectlevel2">
<li><a href="compilation.html#chap:compilation">12.1. Introduction</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:general_design_rationals">12.1.1. General design rationals</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:logging_and_error_reporting">12.1.1.1. Logging and error reporting</a></li>
<li><a href="compilation.html#sec:progress_monitor">12.1.1.2. Progress monitor</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Xtext_Integration">12.1.2. Xtext Integration</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:xtext_default_behaviour">12.1.2.1. Xtext default behaviour</a></li>
<li><a href="compilation.html#sec:n4js_requirements">12.1.2.2. N4JS requirements</a></li>
<li><a href="compilation.html#sec:compiler_discovery_in_ui">12.1.2.3. Compiler discovery in UI</a></li>
<li><a href="compilation.html#sec:compiler_discovery_in_headless">12.1.2.4. Compiler discovery in headless</a></li>
<li><a href="compilation.html#sec:general_generator_implementation">12.1.2.5. General generator implementation</a></li>
<li><a href="compilation.html#sec:general_generator_activation">12.1.2.6. General generator activation</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Overview_of_Input_Models">12.1.3. Overview of the Input Models</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Core_Generator">12.2. Generators</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Compiler_Components">12.2.1. Generator Components</a></li>
<li><a href="compilation.html#sec:Generator_architecture">12.2.2. Generator architecture</a></li>
<li><a href="compilation.html#sec:Unified_Compiler_Configuration">12.2.3. Unified Compiler Configuration</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Transpilers">12.3. Transpilers</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Phases">12.3.1. Overview</a></li>
<li><a href="compilation.html#relation-between-ast-and-im">12.3.2. Relation between AST and IM</a></li>
<li><a href="compilation.html#implementation-overview">12.3.3. Implementation Overview</a></li>
<li><a href="compilation.html#sec:Guidelines_for_Implementing_Transformations">12.3.4. Guidelines for Implementing Transformations</a></li>
<li><a href="compilation.html#symbol-table-in-the-im">12.3.5. Symbol Table in the IM</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:N4JS_to_EcmaScript_Transpiler">12.4. N4JS-to-EcmaScript Transpiler</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Overview_of_Transformations">12.4.1. Overview of Transformations</a></li>
<li><a href="compilation.html#sec:Transpiling_members">12.4.2. Transpiling members</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:Transpiling_members__Delegating_members">12.4.2.1. Techniques for special member handling</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Partial_shadowing_of_getter_setter_pairs">12.4.2.2. Partial shadowing</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Consuming_or_inheriting_members_of_an_interface">12.4.2.3. Consuming or inheriting members of an interface</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Static_polyfill">12.4.2.4. Static polyfill</a></li>
<li><a href="compilation.html#sec:Transpiling_members__API_implementation_stubs">12.4.2.5. API / implementation stubs</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Support_for_incomplete_API_implementation_testing_in_the_N4JS_to_EcmaScript_5_Transpiler">12.4.3. Support for incomplete API implementation testing</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:Modifications_in_Impl_projects">12.4.3.1. Modifications in Impl projects</a></li>
<li><a href="compilation.html#sec:Implementation_of_stub_generation">12.4.3.2. Implementation of stub-generation</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="compilation.html#sec:n4jsc_Headless_Compiler_Interface">12.5. n4jsc Headless Compiler Interface</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:building_the_headless_compiler">12.5.1. building the headless compiler</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="execution.html#_execution">13. Execution</a>
<ul class="sectlevel2">
<li><a href="execution.html#sec:N4JS_Project_Execution_And_Linking_Model">13.1. N4JS Project Execution And Linking Model</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:N4JS_Execution_With_NodeJS">13.1.1. N4JS Execution With NodeJS</a></li>
</ul>
</li>
<li><a href="execution.html#sec:N4JS_Execution_And_Linking_File">13.2. N4JS Execution And Linking File</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:NodeJS_Specific_ELF">13.2.1. NodeJS Specific ELF</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Runners-execution">13.3. Runners</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:N4_Runtime_Environments_Convention">13.3.1. N4 Runtime Environments Convention</a></li>
<li><a href="execution.html#subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment">13.3.2. Passing Information from IDE to Execution Code in Runtime Environment</a></li>
<li><a href="execution.html#subsec:Runners_Design">13.3.3. Runners Design</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Legacy_Execution_Engine">13.4. Legacy Execution Engine</a></li>
<li><a href="execution.html#sec:Design">13.5. Design</a>
<ul class="sectlevel3">
<li><a href="execution.html#sec:Usage_Outside_N4JSIDE">13.5.1. Usage Outside N4JSIDE</a>
<ul class="sectlevel4">
<li><a href="execution.html#sec:Use_Node_with_Maven">13.5.1.1. Use Node with Maven</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Usage_Inside_N4JSIDE">13.5.2. Usage Inside N4JSIDE</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Runtime_Injection">13.6. Runtime Injection</a>
<ul class="sectlevel3">
<li><a href="execution.html#sec:Running_String_Code">13.6.1. Running String Code</a></li>
<li><a href="execution.html#sec:Running_File_Code">13.6.2. Running File Code</a></li>
<li><a href="execution.html#sec:Injection_Code_Example">13.6.3. Injection Code Example</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#_tests">14. Tests</a>
<ul class="sectlevel2">
<li><a href="tests.html#sec:Performance_Tests">14.1. Performance Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Synthetic_Performance_Tests">14.1.1. Synthetic Performance Tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Design_of_Generator">14.1.1.1. Design of Generator</a></li>
<li><a href="tests.html#sec:Design_of_Performance_Test_Execution">14.1.1.2. Design of Performance Test Configuration and Execution</a></li>
<li><a href="tests.html#sec:JUnit_Configuration">14.1.1.3. JUnit Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Test_Configuration">14.1.1.4. JUnitBenchmark Test Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Report_Configuration">14.1.1.5. JUnitBenchmark Report Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Run_Configuration">14.1.1.6. JUnitBenchmark Run Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Example">14.1.1.7. JUnitBenchmark Example</a></li>
<li><a href="tests.html#sec:Note_on_Jenkins_Job">14.1.1.8. Note on Jenkins Job</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:ECMA_Tests">14.2. ECMA Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Grammar_Tests">14.2.1. Grammar Tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Negative_Tests">14.2.1.1. Negative Tests</a></li>
<li><a href="tests.html#sec:Test_Exclusion">14.2.1.2. Test Exclusion</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:Integration_Tests">14.3. Integration Tests</a></li>
<li><a href="tests.html#sec:Test_Helpers">14.4. Test Helpers</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Parameterized_N4JS_Tests">14.4.1. Parameterized N4JS tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:ParameterizedXtextRunner">14.4.1.1. ParameterizedXtextRunner</a></li>
<li><a href="tests.html#sec:TestCodeProvider">14.4.1.2. TestCodeProvider</a></li>
<li><a href="tests.html#sec:Example_Of_Parameterized_Parser_Test">14.4.1.3. Example of parameterized parser test</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:Issue_Suppression">14.5. Issue Suppression</a></li>
<li><a href="tests.html#sec:Xpect_Tests">14.6. Xpect Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Xpect_Test_Setup">14.6.1. Xpect Test Setup</a></li>
<li><a href="tests.html#sec:Xpect_Issue_Suppression">14.6.2. Xpect Issue Suppression</a></li>
<li><a href="tests.html#sec:Xpect_Provided_Test_Methods">14.6.3. Xpect Provided Test Methods</a>
<ul class="sectlevel4">
<li><a href="tests.html#errors">14.6.3.1. errors</a></li>
<li><a href="tests.html#warnings">14.6.3.2. warnings</a></li>
</ul>
</li>
<li><a href="tests.html#sec:N4JS_Specific_Xpect_Test_Methods">14.6.4. N4JS Specific Xpect Test Methods</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:XPECT_noerrors">14.6.4.1. noerrors and nowarnings</a></li>
<li><a href="tests.html#sec:XPECT_scope">14.6.4.2. scope</a></li>
<li><a href="tests.html#sec:XPECT_scopeWithPosition">14.6.4.3. scopeWithPosition</a></li>
<li><a href="tests.html#sec:XPECT_scopeWithResource">14.6.4.4. scopeWithResource</a></li>
<li><a href="tests.html#sec:XPECT_binding">14.6.4.5. binding</a></li>
<li><a href="tests.html#sec:XPECT_linkedPathname">14.6.4.6. linkedPathname</a></li>
<li><a href="tests.html#sec:XPECT_type_of">14.6.4.7. type of</a></li>
<li><a href="tests.html#sec:XPECT_expectedType">14.6.4.8. expectedType</a></li>
<li><a href="tests.html#sec:XPECT_elementKeyword">14.6.4.9. elementKeyword</a></li>
<li><a href="tests.html#sec:XPECT_accessModifier">14.6.4.10. accessModifier</a></li>
<li><a href="tests.html#sec:XPECT_compileResult">14.6.4.11. compileResult</a></li>
<li><a href="tests.html#sec:XPECT_output">14.6.4.12. output</a></li>
<li><a href="tests.html#sec:XPECT_outputRegEx">14.6.4.13. outputRegEx</a></li>
<li><a href="tests.html#sec:XPECT_calculatedAccessModifier">14.6.4.14. calculatedAccessModifier</a></li>
<li><a href="tests.html#sec:XPECT_spec">14.6.4.15. spec</a></li>
<li><a href="tests.html#sec:XPECT_deadCode">14.6.4.16. deadCode</a></li>
<li><a href="tests.html#sec:XPECT_returnOrThrows">14.6.4.17. returnOrThrows</a></li>
<li><a href="tests.html#sec:XPECT_lint">14.6.4.18. lint</a></li>
<li><a href="tests.html#sec:XPECT_lintFails">14.6.4.19. lintFails</a></li>
</ul>
</li>
<li><a href="tests.html#sec:FIXME_Xpect_modifier">14.6.5. FIXME Xpect modifier</a></li>
<li><a href="tests.html#sec:Expectmatrix_Xpect_Test_Methods">14.6.6. Expectmatrix Xpect tests</a></li>
<li><a href="tests.html#xpect-lint-tests">14.6.7. Xpect Lint Tests</a></li>
</ul>
</li>
<li><a href="tests.html#xpect-proposal-tests">14.7. Xpect Proposal Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Validation_vs__Non_Validation">14.7.1. Validation vs. Non-Validation</a></li>
<li><a href="tests.html#sec:General_Proposal_Test_Features">14.7.2. General Proposal Test Features</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Test_Variables">14.7.2.1. Test Variables</a></li>
<li><a href="tests.html#sec:Location_and_Selection">14.7.2.2. at – Location and Selection</a></li>
<li><a href="tests.html#sec:Multi_Line_Expectations_in_Proposal_Tests">14.7.2.3. Multi Line Expectations in Proposal Tests</a></li>
<li><a href="tests.html#sec:Timeout">14.7.2.4. Timeout and Performance</a></li>
</ul>
</li>
<li><a href="tests.html#proposals-verify-existence-of-proposals">14.7.3. proposals – Verify Existence of Proposals</a></li>
<li><a href="tests.html#sec:Verify_displayed_string">14.7.4. display – Verify displayed string</a></li>
<li><a href="tests.html#sec:Apply_Proposal">14.7.5. apply – Apply Proposal</a>
<ul class="sectlevel4">
<li><a href="tests.html#resource-application-in-other-files">14.7.5.1. resource – application in other files</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Content_Assist_Cycling">14.7.6. kind – Content Assist Cycling</a></li>
<li><a href="tests.html#fileValidVerify-validation-status">14.7.7. fileValid – Verify validation status</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Apply_Proposal_And_Execute_Tests">14.8. Apply Proposal And Execute Tests</a></li>
<li><a href="tests.html#sec:Organize_Imports_Test">14.9. Organize Imports Test</a>
<ul class="sectlevel3">
<li><a href="tests.html#organizeimports">14.9.1. organizeImports</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Access_Control_Test">14.10. Access Control Test</a>
<ul class="sectlevel3">
<li><a href="tests.html#test-scenarios">14.10.1. Test Scenarios</a></li>
<li><a href="tests.html#n4js-code-generator">14.10.2. N4JS Code Generator</a></li>
<li><a href="tests.html#xtext-issue-matcher">14.10.3. Xtext Issue Matcher</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Smoke_Tests">14.11. Smoke Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#how-to-handle-smoke-test-errors">14.11.1. How to handle smoke test errors?</a></li>
<li><a href="tests.html#smoketester-and-exceptionanalyzer">14.11.2. SmokeTester and ExceptionAnalyzer</a></li>
</ul>
</li>
<li><a href="tests.html#sec:UI_Tests_with_SWTBot">14.12. UI Tests with SWTBot</a>
<ul class="sectlevel3">
<li><a href="tests.html#writing-swtbot-tests">14.12.1. Writing SWTBot Tests</a></li>
<li><a href="tests.html#running-swtbot-tests">14.12.2. Running SWTBot Tests</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Debugging_UI_Tests">14.13. Debugging UI Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Connecting_to_the_X_server_on_the_build_node">14.13.1. Connecting to the X-server on the build-node</a></li>
<li><a href="tests.html#sec:Tools_to_investigate_the_java_stack">14.13.2. Tools to investigate the java-stack</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="ui_concepts.html#_ui-concepts">15. UI Concepts</a>
<ul class="sectlevel2">
<li><a href="ui_concepts.html#sec:User_Interface_Concepts">15.1. User Interface Concepts</a>
<ul class="sectlevel3">
<li><a href="ui_concepts.html#sec:Eclipse_UI_Concepts">15.1.1. Eclipse UI Concepts</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#sec:Label_Provider">15.1.1.1. Label Provider</a></li>
<li><a href="ui_concepts.html#sec:Markers">15.1.1.2. Markers</a></li>
<li><a href="ui_concepts.html#sec:Commands__Toolbar_and_Menus">15.1.1.3. Commands, Toolbar and Menus</a></li>
<li><a href="ui_concepts.html#sec:Content_Assist">15.1.1.4. Content Assist</a></li>
<li><a href="ui_concepts.html#sec:Quick_Fixes">15.1.1.5. Quick Fixes</a></li>
<li><a href="ui_concepts.html#sec:Quick_Assist">15.1.1.6. Quick Assist</a></li>
<li><a href="ui_concepts.html#sec:Clean_Up_Actions">15.1.1.7. Clean Up Actions</a></li>
<li><a href="ui_concepts.html#sec:Save_Actions">15.1.1.8. Save Actions</a></li>
<li><a href="ui_concepts.html#sec:Auto_Edit">15.1.1.9. Auto Edit</a></li>
<li><a href="ui_concepts.html#sec:Template_Proposals">15.1.1.10. Template Proposals</a></li>
<li><a href="ui_concepts.html#sec:Outline_View___Quick_Outline">15.1.1.11. Outline View / Quick Outline</a></li>
<li><a href="ui_concepts.html#sec:Navigator__Package_Explorer__Project_Explorer">15.1.1.12. Navigator, Package Explorer, Project Explorer</a></li>
<li><a href="ui_concepts.html#sec:Hyperlinking_and_Navigation">15.1.1.13. Hyperlinking and Navigation</a></li>
<li><a href="ui_concepts.html#sec:Syntax_and_Semantic_Coloring">15.1.1.14. Syntax and Semantic Coloring</a></li>
<li><a href="ui_concepts.html#sec:Code_Formatter">15.1.1.15. Code Formatter</a></li>
<li><a href="ui_concepts.html#sec:Wizards">15.1.1.16. Wizards</a></li>
<li><a href="ui_concepts.html#sec:Cheat_Sheets">15.1.1.17. Cheat Sheets</a></li>
<li><a href="ui_concepts.html#sec:Context_sensitive_Help">15.1.1.18. Context-sensitive Help</a></li>
<li><a href="ui_concepts.html#sec:Hovers">15.1.1.19. Hovers</a></li>
<li><a href="ui_concepts.html#sec:Folding">15.1.1.20. Folding</a></li>
<li><a href="ui_concepts.html#sec:Customizable_validation___severity">15.1.1.21. Customizable validation / severity</a></li>
<li><a href="ui_concepts.html#sec:Proposals">15.1.1.22. Proposals</a></li>
</ul>
</li>
<li><a href="ui_concepts.html#sec:Non_Eclipse_UI_Concepts">15.1.2. Non-Eclipse UI Concepts</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#sec:Overlays">15.1.2.1. Overlays</a></li>
<li><a href="ui_concepts.html#sec:Goto__Inferred__Type">15.1.2.2. Goto (Inferred) Type</a></li>
<li><a href="ui_concepts.html#sec:Postfix_Completion">15.1.2.3. Postfix Completion</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="ui_concepts.html#_user-interface-resources">15.2. User Interface Resources</a>
<ul class="sectlevel3">
<li><a href="ui_concepts.html#_icons">15.2.1. Icons</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#_eclipse-platform-icons">15.2.1.1. Eclipse Platform Icons</a></li>
<li><a href="ui_concepts.html#_n4js-specific-icons">15.2.1.2. N4JS Specific Icons</a></li>
<li><a href="ui_concepts.html#_high-resolution-icons">15.2.1.3. High Resolution Icons</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="formatting.html#_formatting">16. Formatting</a>
<ul class="sectlevel2">
<li><a href="formatting.html#sec:FmtObjective">16.1. Objective</a>
<ul class="sectlevel3">
<li><a href="formatting.html#sec:FmtFormatting_Comments">16.1.1. Formatting Comments</a></li>
</ul>
</li>
<li><a href="formatting.html#sec:FmtArchitecture">16.2. Architecture</a>
<ul class="sectlevel3">
<li><a href="formatting.html#sec:Implementation_example">16.2.1. Implementation example</a></li>
</ul>
</li>
<li><a href="formatting.html#sec:FmtFormatter_Implementation_Guidelines">16.3. Formatter Implementation Guidelines</a></li>
<li><a href="formatting.html#sec:FmtConfiguration">16.4. Configuration</a></li>
<li><a href="formatting.html#sec:FmtUI_Integration">16.5. UI Integration</a></li>
<li><a href="formatting.html#sec:FmtUnit_Testing_with_Xpect">16.6. Unit Testing with Xpect</a></li>
</ul>
</li>
<li><a href="external_libraries.html#_external-libraries">17. External Libraries</a>
<ul class="sectlevel2">
<li><a href="external_libraries.html#sec:Major_Components">17.1. Major Components</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#subsec:External_Resources">17.1.1. External Resources</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Workspace">17.1.2. External Library Workspace</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Preference_Store">17.1.3. External Library Preference Store</a></li>
<li><a href="external_libraries.html#subsec:npm_Manager">17.1.4. Library Manager</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Builder_Helper">17.1.5. External Library Builder</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Xtext_Index_Persister">17.1.6. External Library Xtext Index Persister</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Preference_Page">17.1.7. External Library Preference Page</a></li>
</ul>
</li>
<li><a href="external_libraries.html#sec:Headless_External_Library_Support">17.2. Headless External Library Support</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#_custom-npm-settings">17.2.1. Custom npm settings</a></li>
</ul>
</li>
<li><a href="external_libraries.html#sec:lmFutureWork">17.3. Future Work</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#subsec:lmMultipleDependencyScope">17.3.1. Multiple Dependency Scope</a></li>
<li><a href="external_libraries.html#subsec:lmRunTestsFromLibrary">17.3.2. Run Tests from TestLibrary</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="json_support.html#sec:JSON_Support">18. JSON Support</a>
<ul class="sectlevel2">
<li><a href="json_support.html#sec:JSON_Parser">18.1. JSON Parser</a>
<ul class="sectlevel3">
<li><a href="json_support.html#sec:JSON_Parser_Unicode_Escaping">18.1.1. Escaping Unicode Control Characters in String Literals</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Empty_Text">18.1.2. Empty Text</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Nested_Structures">18.1.3. Nested Structures</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Whitespace">18.1.4. Whitespace</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Comments">18.1.5. Comments</a></li>
</ul>
</li>
<li><a href="json_support.html#sec:JSON_Language_Extensions">18.2. JSON Language Extensions</a>
<ul class="sectlevel3">
<li><a href="json_support.html#sec:JSON_Validator_Extensions">18.2.1. JSON Validator Extensions</a>
<ul class="sectlevel4">
<li><a href="json_support.html#sec:File_Specitic_Validator_Extensions">18.2.1.1. File-Specific Validator Extensions</a></li>
<li><a href="json_support.html#sec:JSON_Declarative_JSON_Validator_Extensions">18.2.1.2. Declarative JSON Validator Extensions</a></li>
</ul>
</li>
<li><a href="json_support.html#_json-resource-description-strategy">18.2.2. JSON Resource Description Strategy</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="jsdoc.html#_jsdoc">19. JSDoc</a>
<ul class="sectlevel2">
<li><a href="jsdoc.html#sec:Design_Rationale">19.1. Design Rationale</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#_general-design">19.1.1. General Design</a></li>
<li><a href="jsdoc.html#sec:Type_Expressions">19.1.2. Type Expressions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="docexporter.html#_docexporter">20. DocExporter</a>
<ul class="sectlevel2">
<li><a href="docexporter.html#sec:Specification_Exporter">20.1. Specification Exporter</a></li>
</ul>
</li>
<li><a href="rename_refactoring.html#_rename-refactoring">21. Rename Refactoring</a>
<ul class="sectlevel2">
<li><a href="rename_refactoring.html#_rename-refactoring-ui-interaction">21.1. Rename Refactoring UI interaction</a></li>
<li><a href="rename_refactoring.html#_renameelementprocessor-interaction">21.2. RenameElementProcessor interaction</a></li>
</ul>
</li>
<li><a href="flow_graphs.html#chap:flowgraphs">22. Flow Graphs</a>
<ul class="sectlevel2">
<li><a href="flow_graphs.html#sec:flowgraphs_overview">22.1. Flow graphs overview</a>
<ul class="sectlevel3">
<li><a href="flow_graphs.html#_internal-graph">22.1.1. Internal graph</a></li>
<li><a href="flow_graphs.html#_optimizations">22.1.2. Optimizations</a></li>
<li><a href="flow_graphs.html#_api-for-client-analyses">22.1.3. API for client analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_mapping-from-internal-to-ast-elements">22.1.3.1. Mapping from internal to AST elements</a></li>
<li><a href="flow_graphs.html#_graph-visitor">22.1.3.2. Graph visitor</a></li>
<li><a href="flow_graphs.html#_graph-explorer">22.1.3.3. Graph explorer</a></li>
<li><a href="flow_graphs.html#_branch-walker">22.1.3.4. Branch walker</a></li>
<li><a href="flow_graphs.html#_example-1-compute-string-for-each-path">22.1.3.5. Example 1: Compute string for each path</a></li>
<li><a href="flow_graphs.html#_path-quantor">22.1.3.6. Path quantor</a></li>
</ul>
</li>
<li><a href="flow_graphs.html#_control-flow-analyses">22.1.4. Control flow analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_dead-code-analysis">22.1.4.1. Dead code analysis</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="flow_graphs.html#sec:dataflow">22.2. Dataflow</a>
<ul class="sectlevel3">
<li><a href="flow_graphs.html#_dataflow-graph">22.2.1. Dataflow graph</a></li>
<li><a href="flow_graphs.html#_dataflow-analyses">22.2.2. Dataflow analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_def-def-def-nothing-analysis">22.2.2.1. Def&#8594;Def / Def&#8594;Nothing analysis</a></li>
<li><a href="flow_graphs.html#_def-use-decl-analysis">22.2.2.2. Def|Use&#8592;Decl analysis</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="publish_npms.html#sec:publish-npms-to-public">23. Publish npms</a>
<ul class="sectlevel2">
<li><a href="publish_npms.html#sec:publish-npms-n4js-maven">23.1. Publish n4js-libs to during  maven build</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Hints">Appendix A: Hints</a>
<ul class="sectlevel2">
<li><a href="appendix_a_hints.html#sec:XtextInjection">A.1. Xtext Injection</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#sec:DI_MultipleInjectors_Singletons">A.1.1. Multiple Injectors and Singletons</a>
<ul class="sectlevel4">
<li><a href="appendix_a_hints.html#sec:DI_avoid_duplicate_singletons">A.1.1.1. Avoiding duplicate singletons</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DI_binding_in_shared">A.1.1.1.1. Defining binding in the shared injector</a></li>
<li><a href="appendix_a_hints.html#sec:DI_binding_in_custom">A.1.1.1.2. Defining binding in the custom injector</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:DI_Hints">A.1.2. Dependency Injection Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle">A.1.2.1. Use DI in custom bundle, use DI with extensions</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle_problem">A.1.2.1.1. Problem</a></li>
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle_solution">A.1.2.1.2. Solution</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Access_Other_DSL_Injector">A.1.2.2. How do I get the Guice Injector of my language?</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DSL_Injector_UI_context">A.1.2.2.1. UI context</a></li>
<li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_context">A.1.2.2.2. Non UI context but with injection context</a></li>
<li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_non_injection_context">A.1.2.2.3. Non UI context without injection context</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Cancel_Indicator">A.1.2.3. How do I get cancel indicators in different contexts?</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Eclipse">A.2. Eclipse</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#sec:Show_Xtext_Index">A.2.1. Show the current Xtext index</a></li>
<li><a href="appendix_a_hints.html#sec:Plugin_spy">A.2.2. Plug-in spy</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Maven-hints">A.3. Maven</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#how-to-check-for-maven-mojo-updates">A.3.1. How to check for Maven MOJO updates</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_module-loading">Appendix B: Module Loading</a>
<ul class="sectlevel2">
<li><a href="appendix_b_module_loading.html#sec:Dependency_Management">B.1. Dependency Management</a></li>
<li><a href="appendix_b_module_loading.html#ecmascript-modules">B.2. ECMAScript Modules</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES5_Modules_Systems">B.2.1. ES5 Modules Systems</a></li>
<li><a href="appendix_b_module_loading.html#sec:ES6_Modules">B.2.2. ES6 Modules</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:ECMAScript_Module_Loaders">B.3. ECMAScript Module Loaders</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES6_Module_Loaders">B.3.1. ES6 Module Loaders</a></li>
<li><a href="appendix_b_module_loading.html#sec:Polyfills_for_ES6_Module_Loaders">B.3.2. Polyfills for ES6 Module Loaders</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:es6_module_loader">B.3.2.1. es6-module-loader</a></li>
<li><a href="appendix_b_module_loading.html#sec:SystemJS">B.3.2.2. SystemJS</a></li>
<li><a href="appendix_b_module_loading.html#sec:Demo">B.3.2.3. Demo</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#case-study-typescript">B.4. Case Study : TypeScript</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES6_Modules_Support">B.4.1. ES6 Modules Support</a></li>
<li><a href="appendix_b_module_loading.html#sec:TypeScript_and_Module_Loading">B.4.2. TypeScript and Module Loading</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Cyclic_Dependencies">B.5. Cyclic Dependencies</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:Setup">B.5.1. Setup</a></li>
<li><a href="appendix_b_module_loading.html#sec:Transpile_and_Execute">B.5.2. Transpile and Execute</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Module_Format___AMD">B.5.2.1. Module Format = AMD</a></li>
<li><a href="appendix_b_module_loading.html#sec:Module_Format___CommonJS">B.5.2.2. Module Format = CommonJS</a></li>
<li><a href="appendix_b_module_loading.html#sec:Module_Format___SystemJS">B.5.2.3. Module Format = SystemJS</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Conclusion">B.5.3. Conclusion</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#system.register-as-transpilation-target">B.6. System.register as transpilation target</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:Introduction">B.6.1. Introduction</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:External_Transpilers">B.6.1.1. External Transpilers</a></li>
<li><a href="appendix_b_module_loading.html#sec:Example_of_a_System_register_module">B.6.1.2. Example of a System.register module</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Structure_of_a_System_register_module">B.6.2. Structure of a System.register module</a></li>
<li><a href="appendix_b_module_loading.html#_transpilation-hints">B.6.3. Transpilation Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Handling_Imports">B.6.3.1. Handling Imports</a></li>
<li><a href="appendix_b_module_loading.html#sec:__exportFn__">B.6.3.2. &lt;&lt;exportFn&gt;&gt;</a></li>
<li><a href="appendix_b_module_loading.html#sec:Handling_Exports">B.6.3.3. Handling Exports</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Examples_w__Circular_Dependencies">B.6.4. Examples w/ Circular Dependencies</a></li>
<li><a href="appendix_b_module_loading.html#sec:N4JS_Examples_w__Circular_Dependencies">B.6.5. N4JS Examples w/ Circular Dependencies</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Unresolved_Cyclic_Dependencies">B.6.5.1. Unresolved Cyclic Dependencies</a></li>
<li><a href="appendix_b_module_loading.html#sec:Variables___Functions">B.6.5.2. Examples with Variables &amp; Functions</a></li>
<li><a href="appendix_b_module_loading.html#sec:Classes">B.6.5.3. Examples with Classes</a></li>
<li><a href="appendix_b_module_loading.html#sec:Examples_with_SubClassing">B.6.5.4. Examples with SubClassing</a></li>
<li><a href="appendix_b_module_loading.html#sec:Miscellaneous">B.6.5.5. Miscellaneous</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_resources">B.6.6. Resources</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:CommonJS_as_transpilation_target">B.7. CommonJS as transpilation target</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#_introduction-2">B.7.1. Introduction</a></li>
<li><a href="appendix_b_module_loading.html#sec:Transpilation_Hints">B.7.2. Transpilation Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Import_Statements">B.7.2.1. Import Statements</a></li>
<li><a href="appendix_b_module_loading.html#sec:Export_Statements">B.7.2.2. Export Statements</a></li>
<li><a href="appendix_b_module_loading.html#sec:Tracking_Live_Bindings">B.7.2.3. Tracking Live Bindings</a></li>
<li><a href="appendix_b_module_loading.html#sec:A_complete_example">B.7.2.4. A complete example</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_resources-2">B.7.3. Resources</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_c_license.html#sec:License">Appendix C: License</a></li>
<li><a href="appendix_d_acronyms.html#sec:Acronyms">Appendix D: Acronyms</a></li>
<li><a href="appendix_e_bibliography_and_footnotes.html#_bibliography-and-footnotes">Appendix E: Bibliography and Footnotes</a></li>
</ul>
</div>
</div>
<div id="content"><div class="sect1">
<h2 id="_references"><a class="anchor" href="#_references"></a><a class="link" href="#_references">11. References</a></h2>
<div class="sectionbody">
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title=""></i>
</td>
<td class="content">
This chapter maybe outdated.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="sec:usecases"><a class="anchor" href="#sec:usecases"></a><a class="link" href="#sec:usecases">11.1. Use cases</a></h3>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Compilation
</td>
<td class="hdlist2">
<p>for deciding in incremental builder which resources requires a recompilation</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Editing
</td>
<td class="hdlist2">
<p>Dirty state calculation: for deciding which resources needs to be reparsed as references have changed</p>
</td>
</tr>
<tr>
<td class="hdlist1">
UI
</td>
<td class="hdlist2">
<p>Such as <kbd>Find references</kbd>, find all places in the workspaces that points to the selected element</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Tools
</td>
<td class="hdlist2">
<p>requiring references, such as refactorings, e.g., rename refactoring: apply the renaming of the element also to all references to it (like find by references)</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:calculation_algorithm"><a class="anchor" href="#sec:calculation_algorithm"></a><a class="link" href="#sec:calculation_algorithm">11.2. Calculation algorithm</a></h3>
<div class="sect3">
<h4 id="sec:Xtext_default_implementation"><a class="anchor" href="#sec:Xtext_default_implementation"></a><a class="link" href="#sec:Xtext_default_implementation">11.2.1. Xtext default implementation</a></h4>
<div class="paragraph">
<p>Using Reference Descriptions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>default implementation contained in method <code>createReferenceDescriptions</code> of <code>o.e.x.resource.impl.DefaultResourceDescriptionStrategy</code></p>
</li>
<li>
<p>iterates over all EReferences of the EClass of the current element</p>
</li>
<li>
<p>navigates all references and resolves them (already done before in DefaultResourceDescription.computeReferenceDescriptions)</p>
</li>
<li>
<p>create reference description objects for all these references</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In case of N4JS and the types, reference descriptions are also created for references to types model elements (definedType) and for references from Types element to AST.</p>
</div>
<div class="paragraph">
<p>We do not use this default implementation for two reasons:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>expensive</p>
</li>
<li>
<p>Default implementation of reference descriptions only calculates the direct dependencies but not the transitive ones + the calculation of the URIs is very expensive.</p>
</li>
</ol>
</div>
</div>
<div class="sect3">
<h4 id="sec:N4_implementation"><a class="anchor" href="#sec:N4_implementation"></a><a class="link" href="#sec:N4_implementation">11.2.2. N4JS implementation</a></h4>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>the Xtext default implementation is disabled by let <code>N4JSResourceDescription.computeReferenceDescriptions</code> return an empty list. Also the bound <code>N4JSDescriptionUtils</code> returns an empty list for collectOutgoingReferences</p>
</li>
<li>
<p>Calculating <em>direct references</em> are only done inside <code>N4JSResourceDescription.getImportedNames</code> (that uses newly introduced <code>N4JSCrossReferenceComputer.computeCrossRefs</code> for collecting all direct dependencies) - here only (parameterized) type refs, types and identifiable elements are collected</p>
</li>
<li>
<p>collect all <em>transitive dependencies</em>, i.e. all super classes, consumed roles and implemented interfaces in the type hierarchy and add their resources as dependency (this is done in <code>N4JSResourceDescription.getImportedNames</code> (after calculating all direct dependencies with <code>N4JSResourceDescriptionStrategy</code>)</p>
</li>
<li>
<p>bind <code>N4JSReferenceQueryExecutor</code> as a custom implementation to calculate the target URIs for an given target element and bind <code>N4JSReferenceFinder</code> as a custom implementation to calculate reference descriptions to be used by the default Xtext found references UI (use case UI)</p>
</li>
</ol>
</div>
<div class="paragraph">
<p><code>ClusteringBuilderState.doUpdate</code> calculates if a dependent resource has changed (in the context of calculating the <code>DefaultResourceDescriptionDelta</code> out of the old and new resource descriptions). Each resource description consists of <code>EObjectDescriptions</code>. The <code>EObjectDescription</code> for <code>Script</code> also contains the types model (<code>TModule</code>) for the resource. The references between resources are implemented via the type model. If it has changed (compared with the user data of the old <code>EObjectDescription</code>) then all other resource descriptions registered as been dependent on the resource (the qualified names of the resource descriptions are serialized as imported names within the resource description) will be notified that a reparse is needed.</p>
</div>
<div class="paragraph">
<p>For <em>dirty state</em> the same behavior is achieved via the dirty state editor support using the resource set of the editor (instead the file system resources).</p>
</div>
<div class="paragraph">
<p>As the primitive and built-in types are fixed they are ignored when calculating the dirty state. When calculating dependending resources and dirty state the reference of an AST element to its defining type is ignored as is the reference from the type to its AST element</p>
</div>
<div class="paragraph">
<p><a href="#fig:cd_classes">Classes</a> shows the different entry points (user actions) and classes involved in the process.</p>
</div>
<div id="fig:cd_classes" class="imageblock center">
<div class="content">
<img src="chapters/11_references/images/cd_classes.svg" alt="title-"Reference handling"">
</div>
</div>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:PerformanceOfDependencyCalculation"><a class="anchor" href="#sec:PerformanceOfDependencyCalculation"></a><a class="link" href="#sec:PerformanceOfDependencyCalculation">11.3. Performance Of Dependency Calculation</a></h3>
<div class="paragraph">
<p>Concerning frequency and contexts it is clear, that triggering <code>Find references</code> and rename refactoring is not as frequent as editing (n4)js files that leads to dirty state (very often as happens when editing) and to trigger compilation (at file save, also often). Calculating if a resource is affected by a change (dirty state calculation) may not be too expensive. But running compilation for too many files (or the wrong set of files) due to incorrect dirty state calculation is expensive.</p>
</div>
<div class="paragraph">
<p><code>N4JSResourceDescription.getImportedNames</code> is invoked on every edit of a file in the editor, so on every edit the complete content has to be retraversed for possible new references (expensive but not avoidable). For the types of all found references the super types have to recalculated. Traversing the type hierarchy shouldn’t be too expensive.</p>
</div>
<div class="paragraph">
<p>Possible optimization could be:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>caching of traversing referenced types whose resources had not changed since last edit</p>
</li>
<li>
<p>not traversing types that are imported but non of their features are used within the current resource</p>
</li>
</ol>
</div>
<div class="paragraph">
<p><em>Those optimization should be done only if there are real performance issues are discovered.</em></p>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:kinds_of_references"><a class="anchor" href="#sec:kinds_of_references"></a><a class="link" href="#sec:kinds_of_references">11.4. Kinds of references</a></h3>
<div class="sect3">
<h4 id="sec:Cross_References_to_be_ignored"><a class="anchor" href="#sec:Cross_References_to_be_ignored"></a><a class="link" href="#sec:Cross_References_to_be_ignored">11.4.1. Cross References to be ignored</a></h4>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Element</th>
<th class="tableblock halign-left valign-top">Reference</th>
<th class="tableblock halign-left valign-top">Explanation</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">TypeDefiningElement</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">definedType: Type</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">always inner resource change (e.g., Functions, Classifier)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">types::Type</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">astElement</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">as always inner resource change</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ImportDeclaration</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">importedModule: TModule</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">only affected if the resource name changes (and such a change cannot be performed dirty)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ContinueStatement</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">label: LabelledStatement</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">always inner resource changes</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">BreakStatement</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">label: LabelledStatement</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">always inner resource changes</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">types::PrimitiveType</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">autocoercedObject: TClassifier</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">fixed (immutable) and internal</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3 language-n4js">
<h4 id="sec:Cross_References_to_be_handled"><a class="anchor" href="#sec:Cross_References_to_be_handled"></a><a class="link" href="#sec:Cross_References_to_be_handled">11.4.2. Cross References to be handled</a></h4>
<div class="paragraph">
<p>Cross References</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>types::ParameterizedTypeRef &#8594; declaredType : Type</p>
</li>
<li>
<p>* &#8594; N4GetterDeclaration: N4FieldDeclaration type, but references to getter can be done also done from outside</p>
</li>
<li>
<p>* &#8594; N4SetterDeclaration: undef, references to setter can be done also done from outside</p>
</li>
<li>
<p>types::PrototypeTypeRef &#8594; type : Type</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Contained <code>ParameterizedTypeRef</code> and <code>TypeVariables</code> (that internally references to <code>Type</code>):</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>references to declared super types of a type (Class, Role, Interface), i.e. superType, consumedRoles, implementedInterfaces</p>
</li>
<li>
<p>TypeVariable &#8594; declaredUpperBounds</p>
</li>
<li>
<p>References in type arguments:</p>
<div class="ulist">
<ul>
<li>
<p>Wildcards &#8594; upper and lower bounds, e.g. <code>var List&lt;? super A&gt; l1;</code></p>
</li>
<li>
<p>direct type references, e.g. <code>var List&lt;A&gt; l;</code></p>
</li>
</ul>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>Cross References to IdentifiableElement (types):</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>IdentifierRef &#8594; id : IdentifiableElement</p>
</li>
<li>
<p>NamedImportSpecifier &#8594; importedElement : IdentifiableElement</p>
</li>
<li>
<p>ParameterizedPropertyAccessExpression &#8594; property : IdentifiableElement</p>
</li>
<li>
<p>PropertyAccessExpression &#8594; property : IdentifiableElement</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Contained IdentifierRef (that internally references to IdentifiableElement):</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>ParameterizedCallExpression &#8594; target</p>
</li>
<li>
<p>as PrimaryExpression in MemberExpression</p>
</li>
</ol>
</div>
</div>
</div>
<div class="sect2">
<h3 id="sec:transitive_dependencies"><a class="anchor" href="#sec:transitive_dependencies"></a><a class="link" href="#sec:transitive_dependencies">11.5. Transitive dependencies</a></h3>
<div class="paragraph">
<p>Besides the direct dependencies we also need the transitive dependencies, as demonstrated in the following example.</p>
</div>
<div id="ex:transdepex" class="listingblock">
<div class="title">Transitive Dependency</div>
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class A {
    public myMethod()
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Transitive Dependency pt.2</div>
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class B extends my/test/A {
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Transitive Dependency pt.3</div>
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class C extends my/test/B {
    myMethodC() {
        this.myMethod()
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the name of <code>myMethod</code> in A changes, C should get dirty. This can get more complicated, if, e.g., a method in a consumed role is renamed, which then leads to binding references to super types.</p>
</div>
<div class="paragraph">
<p>Therefore all direct and indirect super types are calculated (including super classes, consumed roles and implemented interfaces) for all found directly referenced types. The qualified names of their resources are added to the list of imported names. <sup class="footnote">[<a id="_footnoteref_12" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_12" title="View footnote.">12</a>]</sup></p>
</div>
<div class="paragraph">
<p>Other transitive dependencies:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>call of member mixed by a consumed role</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>role is consumed by role consumed by this class</p>
</li>
<li>
<p>role is consumed by class inherited by this class</p>
</li>
</ol>
</div>
</li>
<li>
<p>call of member available by implemented interface</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>interface is implemented by role consumed by this class</p>
</li>
<li>
<p>interface is implemented by class inherited by this class</p>
</li>
</ol>
</div>
</li>
<li>
<p>call of member available by extended class</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>class is extended by class inherited by this class</p>
</li>
</ol>
</div>
</li>
<li>
<p>chained method calls</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>method is of type that itself has members which are directly called, so the type is not directly imported or referenced by name in the caller but indirectly required</p>
</li>
<li>
<p>method is of type that itself inherits members which are directly called, so the type (and its super types) is not directly imported or referenced by name in the caller but indirectly required</p>
</li>
</ol>
</div>
</li>
</ol>
</div>
<div class="exampleblock">
<div class="content">
<div class="paragraph">
<p>Each type is defined in its own file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class MyClassOne  {
    myMethodOne() {
        var MyClassTwo instance;
        instance.getElement().myMethodThree()
    }
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class MyClassTwo  {
    MyClassThree getElement() {
        return new MyClassThree;
    }
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class MyClassThree  {
    void myMethodThree() {}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If <code>myMethodThree</code> is renamed this should affect MyClassOne.</p>
</div>
<div class="paragraph">
<p>Note that the method call in <code>MyClassOne</code> directly binds to the method in <code>MyClassThree</code>. However, the dependencies are only managed by means of types. So, from that perspective, the dependency between <code>MyClassOne</code> and <code>MyClassThree</code> is indirect.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class MyClassOne  {
    void myMethodOne() {
        var MyClassTwo instance;
        instance.myMethodTwo().getElement().myMethodFour()
    }
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class MyClassTwo {
    MyClassThree&lt;MyClassFour&gt; myMethodTwo() {
        return null;
    }
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class MyClassThree&lt;T extends MyClassFour&gt;  {
    T element;

    T getElement() {
        return this.element;
    }
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">export class MyClassFour  {
    void myMethodFour() {
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If <code>myMethodFour</code> is renamed this should affect <code>MyClassOne</code>.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>More examples are found in the tests (cf. <code>..ide.n4js.dirtystate.BuilderParticipantPluginTest</code> and <code>&#8230;&#8203;BuilderParticipantPluginUITest</code>)</p>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:find-references"><a class="anchor" href="#sec:find-references"></a><a class="link" href="#sec:find-references">11.6. Find references</a></h3>
<div class="paragraph">
<p>Find references is perceived as a feature in Eclipse IDE, but its implementation can also be useful in a headless scenario, e.g. in the compiler to drop dead code.
Therefore, as opposed to the Xtext default implementations, the code was refactored to split the parts that depend on the UI from the non-UI dependent logic (see <code>org.eclipse.n4js.findReferences</code> vs. <code>org.eclipse.n4js.ui.search</code>).</p>
</div>
<div class="sect3">
<h4 id="_background"><a class="anchor" href="#_background"></a><a class="link" href="#_background">11.6.1. Background</a></h4>
<div class="paragraph">
<p>Since no reference descriptions are stored in the index for N4JS resources, the cross references have to be found by other means.
That is, the list of imported names is used as an indicator to find resources that have a potential dependency to the searched element.
These resources have to be checked thoroughly.
That is, their clear text representation is checked at a first step against the clear text representation of the found element before the resource is fully loaded and cross references are resolved.</p>
</div>
<div class="paragraph">
<p>The decision to drop reference descriptions from the index was deliberate since they would only report bogus information in the context of inheritance, e.g. a method <code>getA</code> of type <code>B</code> my be overridden by <code>getA</code> in type <code>C</code>.
Concrete bindings against <code>C.getA</code> should also be reported as references to <code>B.getA</code> since they identify the same public API of the type hiearchy around <code>B</code>.
Therefore reference descriptions could not be used to find dependencies between source snippets.</p>
</div>
</div>
<div class="sect3">
<h4 id="_how-find-references-work"><a class="anchor" href="#_how-find-references-work"></a><a class="link" href="#_how-find-references-work">11.6.2. How Find References Work</a></h4>
<div class="paragraph">
<p>Methods for finding references are provided Xtext&#8217;s interface <code>IReferenceFinder</code> and can be used both by the UI or headlessly.
The N4JS implementation of this interface for the N4JS language is the class <code>ConcreteSyntaxAwareReferenceFinder</code>.
One of the key methods defined by the <code>IReferenceFinder</code> is <code>void findAllReferences(TargetURIs, IResourceAccess, IResourceDescriptions, Acceptor, IProgressMonitor)</code> that finds all places in all resources of the index whereby those places cross-reference one of the URIs contained in <code>TargetURIs</code> .</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>TargetURIs</code> contains the set of URIs to be searched. The caller of <code>IReferenceFinder</code> is responsible for collecting the <code>Target URIs</code> to be searched.</p>
</li>
<li>
<p><code>IResourceAccess</code> is used to search local references. This is needed because local references are usually not index.</p>
</li>
<li>
<p><code>IResourceDescriptions</code> is the indexed.</p>
</li>
<li>
<p><code>Acceptor</code> is called when a reference is found.</p>
</li>
<li>
<p><code>IProgressMonitor</code> is used for showing progress bar (can be null).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In the following, we will have a look at the workflow to find references when triggered in the UI.
After understanding the UI case, the workflow of find references in the headless case should be self-explanatory.</p>
</div>
<div class="paragraph">
<p><a href="#fig:findreference_workflow">Find reference workflow</a> shows the workflow of find references when triggered in the UI.</p>
</div>
<div id="fig:findreference_workflow" class="imageblock center">
<div class="content">
<img src="chapters/11_references/images/findreference_workflow.svg" alt="title-"Find reference workflow"">
</div>
</div>
<div class="paragraph">
<p>The following example will be used for explanation.</p>
</div>
<div class="listingblock">
<div class="title">A.n4js</div>
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">import {B} from "B";
let b = new B(); // B here is an IdentifierRef referring to TClass B in B.n4js</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">B.n4js</div>
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">export public class B {}</code></pre>
</div>
</div>
<div class="sect4">
<h5 id="_step-1-convert-cursor-position-to-declared-element"><a class="anchor" href="#_step-1-convert-cursor-position-to-declared-element"></a><a class="link" href="#_step-1-convert-cursor-position-to-declared-element">11.6.2.1. Step 1: Convert Cursor Position to Declared Element</a></h5>
<div class="paragraph">
<p>This step is represented by the purple color in <a href="#fig:findreference_workflow">Find reference workflow</a> diagram.</p>
</div>
<div class="paragraph">
<p>In the IDE, for the sake of convenience, we allow the user to find references of an arbitrary element at the current cursor.
For instance, while the cursor is currently at <code>IdentifierRef B</code> in the <code>NewExpression</code> in <code>A.n4js</code>, the user may want to find all references to <code>B</code>.
In those cases, we first need to find declaration element of <code>IdentifierRef B</code> which is <code>TClass B</code>. The Target URIs then contains a single URI to <code>TClass B</code>.
In diagram <a href="#fig:findreference_workflow">Find reference workflow</a>, the classe <code>EObjectAtOffsetHelper</code> can convert the current cursor position into a declared element.</p>
</div>
</div>
<div class="sect4">
<h5 id="_step-2-convert-declared-element-to-target-uris"><a class="anchor" href="#_step-2-convert-declared-element-to-target-uris"></a><a class="link" href="#_step-2-convert-declared-element-to-target-uris">11.6.2.2. Step 2: Convert Declared Element to Target URIs</a></h5>
<div class="paragraph">
<p>This step is represented by the yellow color in <a href="#fig:findreference_workflow">Find reference workflow</a> diagram.</p>
</div>
<div class="paragraph">
<p>The Target URIs contains the URIs whose references are to be searched.
The caller guarantees that <em>Target URIs contain only URIs to declared elements, i.e. definitions</em>.
For example, if we want to find references for <code>N4ClassDeclaration B</code> in <code>B.n4js</code>, the target URIs contains a URI to the AST node <code>N4ClassDeclaration B</code> and a URI to the TModule node <code>TClass B</code>.
Note that, in addition to the URI to the AST node <code>N4ClassDeclaration B</code>, the URI to the derived TModule node <code>TClass B</code> is also needed because <code>N4ClassDeclaration</code> can never be a target of a cross reference.
In the diagram <a href="#fig:findreference_workflow">Find reference workflow</a> , the classes depicted in yellow color are responsible for converting declared elements to <code>Target URIs</code> taking care of the derived <code>TModule</code> nodes.</p>
</div>
</div>
<div class="sect4">
<h5 id="_step-3-filter-potential-resources"><a class="anchor" href="#_step-3-filter-potential-resources"></a><a class="link" href="#_step-3-filter-potential-resources">11.6.2.3. Step 3: Filter Potential Resources</a></h5>
<div class="paragraph">
<p>This step is represented by the green color in <a href="#fig:findreference_workflow">Find reference workflow</a> diagram.</p>
</div>
<div class="paragraph">
<p>The general algorithm for finding references is to traverse the AST of each resource in the index and check each AST node if it has a cross reference to one of the URI in the <code>Target URIs</code>.
However, this is too expensive because potentially all resources in the index have to be loaded.
We need some way to quickly decide for a resource description if the corresponding resource may potentially contain the references before actually loading it for a more thorough search.
This is done using two pieces of information:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>typesOrModulesToFind</code>: the set containing the fully qualified names of the <code>type</code> and <code>module</code> of the declaration to be searched. This set is calculated in the class <code>TargetURIKey</code>.</p>
</li>
<li>
<p><code>imported names</code>: the set exposed by <code>ResourceDescription</code> that contains the types needed by the underlying resource. The implementation for calculating imported names can be found in the class <code>N4JSResourceDescription</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In our example, supposed that we are finding references for <code>class B</code>. The <code>typesOrModulesToFind</code> contains fully qualified names to <code>N4ClassDeclaration B</code> and <code>module B</code>, i.e. <code>B.B</code> and <code>B</code>.
The <code>imported names</code> of the resource description of <code>A.n4js</code> contains fully qualified names to <code>module B</code>, <code>class B</code>, i.e. <code>B</code> and <code>B.B</code>.
Since the set of imported names of <code>A.n4js</code> contains elements in <code>typesOrModulesToFind</code>, this resource is searched thoroughly for references.</p>
</div>
</div>
<div class="sect4">
<h5 id="_step-4-search-references-in-resource"><a class="anchor" href="#_step-4-search-references-in-resource"></a><a class="link" href="#_step-4-search-references-in-resource">11.6.2.4. Step 4: Search References in Resource</a></h5>
<div class="paragraph">
<p>If a resource is considered as a candidate for a more thorough search in Step 3, it is loaded.
Its AST is traversed and at each AST node we check if there is a cross reference to one of the Target URIs (Step 1).
If yes, the AST node is collected in the set of found references.
See class <code>ConcreteSyntaxAwareReferenceFinder</code> for implementation details.</p>
</div>
<div class="paragraph">
<p>The UI dependent logic may apply additional filters to drop references that are not relevant to the user, e.g. the reference from an AST element to its inferred type and vice versa (see <code>N4JSReferenceQueryExecutor.isToBeIgnored(EReference)</code>).</p>
</div>
</div>
<div class="sect4">
<h5 id="_limitations-and-possible-enhancements"><a class="anchor" href="#_limitations-and-possible-enhancements"></a><a class="link" href="#_limitations-and-possible-enhancements">11.6.2.5. Limitations and Possible Enhancements</a></h5>
<div class="paragraph">
<p>Other noteworthy limitations and potential enhancements of the current implementations are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Semantics: Only references that are available in the model as real references are reported. Even though <code>getB()</code> in <code>myA.getB().getC()</code> may return an instance of type <code>B</code>, there is no reference reported to B in that expression, though a reference to a member of B would be reported for <code>getC</code>.</p>
</li>
<li>
<p>Visibility constraints are not applied and thus do not reduce the search scope to allow the report of invalidly established references in a later validation.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 0.9<br>
Last updated 2019-08-08 13:15:33 CEST
</div>
</div>
<!-- ************* docinfo-footer *************************************************************** -->
<div class="Grid social" style="color:#d5dfea">
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <h2>Quick Links</h2>
    <ul>
      <li><a href="../downloads.html">Download</a></li>
      <li><a href="../userguides/index.html">Documentation</a></li>
      <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
      <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
      <li><a href="http://n4js.blogspot.de/">Blog</a></li>
      <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
      <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
      <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
      <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
      <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
      <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
      <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
    </ul>
  </div>
  <div style="clear: both; height: 0; overflow: hidden;"></div>
</div>

<!-- ************* UI Scripts ************* -->
<script type="text/javascript" src="scripts/back-to-top.js"></script>

<script type="text/javascript" src="scripts/treeview.js"></script>
<script type="text/javascript" src="scripts/toc.js"></script>

<!-- ************* Prism.js Syntax Highlighting ************* -->
<script src="scripts/prism.js"></script>

<script type="text/javascript">
	// Add the 'toclist' id for search function
	$(".toc2 > ul").attr('id', 'toclist');
	// Generate a Search input form
	$("#toclist > li:first-of-type").before('<input type="text" id="pagesearch" onkeyup="search()" placeholder="Search for section...">');
	$("#toclist > li:first-of-type").before('<i id="clear" class="fa fa-times-circle-o"></i>');
	$("#clear").click(function(){
	    $("#pagesearch").val('');
	    search();
	    $('.toc2 > ul').treeView('collapseAll');
	});
	// intialize Treeview.js
	$(".toc2 > ul").treeView();
	// Initialize Scrollspy
</script>
<!-- ************* docinfo-footer *************************************************************** -->
</body>
</html>